home *** CD-ROM | disk | FTP | other *** search
/ Windows Game Programming for Dummies (2nd Edition) / WinGamProgFD.iso / mac / DirectX SDK / DXSDK / include / DShowIDL / mediaobj.idl < prev    next >
Text File  |  2001-10-08  |  13KB  |  412 lines
  1. //------------------------------------------------------------------------------
  2. // File: MediaObj.idl
  3. //
  4. // Desc: Define the interfaces for DirectX Media Objects.  This file will be
  5. //       processed by the MIDL tool to produce mediaobj.h and proxy-stub code.
  6. //
  7. // Copyright (c) 1999-2001, Microsoft Corporation.  All rights reserved.
  8. //------------------------------------------------------------------------------
  9.  
  10.  
  11. import "unknwn.idl";
  12. import "objidl.idl";
  13.  
  14. //  DMO_MEDIA_TYPE structure
  15.  
  16. cpp_quote("#ifdef __strmif_h__")
  17. cpp_quote("typedef AM_MEDIA_TYPE DMO_MEDIA_TYPE;")
  18. cpp_quote("#else")
  19. typedef struct _DMOMediaType {
  20.     GUID     majortype;
  21.     GUID     subtype;
  22.     BOOL     bFixedSizeSamples;
  23.     BOOL     bTemporalCompression;
  24.     ULONG    lSampleSize;
  25.     GUID     formattype;
  26.     IUnknown *pUnk;
  27.     ULONG    cbFormat;
  28.     [size_is(cbFormat)] BYTE * pbFormat;
  29. } DMO_MEDIA_TYPE;
  30. typedef LONGLONG REFERENCE_TIME;
  31. cpp_quote("#endif")
  32.  
  33.  
  34. // Per-buffer flags that apply to input buffers
  35. enum _DMO_INPUT_DATA_BUFFER_FLAGS {
  36.     DMO_INPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
  37.     DMO_INPUT_DATA_BUFFERF_TIME            = 0x00000002,
  38.     DMO_INPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004
  39. };
  40.  
  41. // Per-buffer flags that apply to output buffers.
  42. enum _DMO_OUTPUT_DATA_BUFFER_FLAGS {
  43.     DMO_OUTPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
  44.     DMO_OUTPUT_DATA_BUFFERF_TIME            = 0x00000002,
  45.     DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004,
  46.  
  47.     //
  48.     // This flag means the object could have generated more data for this
  49.     // output stream, even with no additional input from any input stream,
  50.     // but the output buffer did not have sufficient room.
  51.     //
  52.     DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE      = 0x01000000
  53. };
  54.  
  55. // Flags returned by GetInputStatus()
  56. enum _DMO_INPUT_STATUS_FLAGS {
  57.     //
  58.     // ACCEPT_DATA indicates that the input stream is ready to accept
  59.     // new data via ProcessInput().
  60.     //
  61.     DMO_INPUT_STATUSF_ACCEPT_DATA   = 0x00000001
  62. };
  63.  
  64. // Flags returned by GetInputStreamInfo()
  65. enum _DMO_INPUT_STREAM_INFO_FLAGS {
  66.     DMO_INPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
  67.     DMO_INPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
  68.     DMO_INPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
  69.     DMO_INPUT_STREAMF_HOLDS_BUFFERS            = 0x00000008
  70. };
  71.  
  72. // Flags returned by GetOutputStreamInfo()
  73. enum _DMO_OUTPUT_STREAM_INFO_FLAGS {
  74.     DMO_OUTPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
  75.     DMO_OUTPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
  76.     DMO_OUTPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
  77.     DMO_OUTPUT_STREAMF_DISCARDABLE              = 0x00000008,
  78.     DMO_OUTPUT_STREAMF_OPTIONAL                 = 0x00000010
  79. };
  80.  
  81. //  SetType flags
  82. enum _DMO_SET_TYPE_FLAGS {
  83.     DMO_SET_TYPEF_TEST_ONLY   = 0x00000001,// check but don't set
  84.     DMO_SET_TYPEF_CLEAR       = 0x00000002 // unset
  85. };
  86.  
  87. //  Process Output Flags
  88. enum _DMO_PROCESS_OUTPUT_FLAGS {
  89.     DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER = 0x00000001 //  Discard
  90. };
  91.  
  92. // Buffer wrapper interface
  93. [
  94.     object,
  95.     uuid(59eff8b9-938c-4a26-82f2-95cb84cdc837)
  96. ]
  97. interface IMediaBuffer : IUnknown
  98. {
  99.     HRESULT SetLength(
  100.        DWORD cbLength
  101.     );
  102.     HRESULT GetMaxLength(
  103.        [out] DWORD *pcbMaxLength
  104.     );
  105.     HRESULT GetBufferAndLength(
  106.        [out] BYTE **ppBuffer,  // not filled if NULL
  107.        [out] DWORD *pcbLength // not filled if NULL
  108.     );
  109. }
  110.  
  111. //
  112. // Output buffer info structure: one of these must be passed in for each
  113. // output stream with every ProcessOutput() call
  114. // All [out] fields should be
  115. // assumed undefined if ProcessOutput() failed
  116. //
  117. typedef struct _DMO_OUTPUT_DATA_BUFFER {
  118.  
  119.     IMediaBuffer *pBuffer; // [in] can be NULL
  120.  
  121.     // ProcessOutput() must set any appropriate flags and zero out the rest.
  122.     DWORD dwStatus; // [out] DMO_OUTPUT_DATA_BUFFERF_XXX (INCOMPLETE, etc.)
  123.  
  124.     //
  125.     // Each of these is valid if the corresponding flag is set in dwStatus
  126.     //
  127.     REFERENCE_TIME rtTimestamp; // [out]
  128.     REFERENCE_TIME rtTimelength; // [out]
  129. } DMO_OUTPUT_DATA_BUFFER, *PDMO_OUTPUT_DATA_BUFFER;
  130.  
  131.  
  132. //  Interface supported by media objects
  133. [
  134.     object,
  135.     uuid(d8ad0f58-5494-4102-97c5-ec798e59bcf4)
  136. ]
  137. interface IMediaObject : IUnknown
  138. {
  139.  
  140. //
  141. // Stream enumeration
  142. //
  143.         HRESULT GetStreamCount(
  144.                 [out] DWORD *pcInputStreams,
  145.                 [out] DWORD *pcOutputStreams
  146.         );
  147.         HRESULT GetInputStreamInfo(
  148.                 DWORD dwInputStreamIndex, // 0-based
  149.                 [out] DWORD *pdwFlags // HOLDS_BUFFERS
  150.         );
  151.         HRESULT GetOutputStreamInfo(
  152.                 DWORD dwOutputStreamIndex, // 0-based
  153.                 [out] DWORD *pdwFlags      // Media object sets to 0
  154.         );
  155.  
  156. //
  157. // Mediatypes
  158. //
  159.         //
  160.         // GetType - iterate through media types supported by a stream.
  161.         // Returns S_FALSE if the type index is out of range ("no more types").
  162.         //
  163.         HRESULT GetInputType(
  164.                 DWORD dwInputStreamIndex,
  165.                 DWORD dwTypeIndex, // 0-based
  166.                 [out] DMO_MEDIA_TYPE *pmt
  167.         );
  168.         HRESULT GetOutputType(
  169.                 DWORD dwOutputStreamIndex,
  170.                 DWORD dwTypeIndex, // 0-based
  171.                 [out] DMO_MEDIA_TYPE *pmt
  172.         );
  173.  
  174.         //
  175.         // SetType - tell the object the type of data it will work with.
  176.         //
  177.         HRESULT SetInputType(
  178.                 DWORD dwInputStreamIndex,
  179.                 [in] const DMO_MEDIA_TYPE *pmt,
  180.                 DWORD dwFlags // test only
  181.         );
  182.         HRESULT SetOutputType(
  183.                 DWORD dwOutputStreamIndex,
  184.                 [in]  const DMO_MEDIA_TYPE *pmt,
  185.                 DWORD dwFlags // test only
  186.         );
  187.  
  188.         //
  189.         // GetCurrentType - get the last mediatype supplied via SetType.
  190.         // Returns S_FALSE if SetType has not been called.
  191.         //
  192.         HRESULT GetInputCurrentType(
  193.                 DWORD dwInputStreamIndex,
  194.                 [out] DMO_MEDIA_TYPE *pmt
  195.         );
  196.         HRESULT GetOutputCurrentType(
  197.                 DWORD dwOutputStreamIndex,
  198.                 [out] DMO_MEDIA_TYPE *pmt
  199.         );
  200.  
  201. //
  202. // SizeInfo
  203. //
  204.         //
  205.         // GetSizeInfo - Get buffer size requirementes of a stream.
  206.         //
  207.         // If buffer size depends on the media type used, the object should
  208.         // base its response on the most recent media type set for this stream.
  209.         // If no mediatype has been set, the object may return an error.
  210.         //
  211.         HRESULT GetInputSizeInfo(
  212.                 DWORD dwInputStreamIndex,
  213.                 [out] DWORD *pcbSize, // size of input 'quantum'
  214.                 [out] DWORD *pcbMaxLookahead, // max total bytes held
  215.                 [out] DWORD *pcbAlignment  // buffer alignment requirement
  216.         );
  217.         HRESULT GetOutputSizeInfo(
  218.                 DWORD dwOutputStreamIndex,
  219.                 [out] DWORD *pcbSize, // size of output 'quantum'
  220.                 [out] DWORD *pcbAlignment  // buffer alignment requirement
  221.         );
  222.  
  223. //
  224. // Latency methods
  225. //
  226.         HRESULT GetInputMaxLatency(
  227.                 DWORD dwInputStreamIndex,
  228.                 [out] REFERENCE_TIME *prtMaxLatency
  229.         );
  230.         HRESULT SetInputMaxLatency(
  231.                 DWORD dwInputStreamIndex,
  232.                 REFERENCE_TIME rtMaxLatency
  233.         );
  234.  
  235. //
  236. // Streaming / state methods
  237. //
  238.         //
  239.         // Flush() - discard any buffered data.
  240.         //
  241.         HRESULT Flush();
  242.  
  243.         //
  244.         // Send a discontinuity to an input stream.  The object will not
  245.         // accept any more data on this input stream until the discontinuity
  246.         // has been completely processed, which may involve multiple
  247.         // ProcessOutput() calls.
  248.         //
  249.         HRESULT Discontinuity(DWORD dwInputStreamIndex);
  250.  
  251.         //
  252.         // If a streaming object needs to perform any time consuming
  253.         // initialization before it can stream data, it should do it inside
  254.         // AllocateStreamingResources() rather than during the first process
  255.         // call.
  256.         //
  257.         // This method is NOT guaranteed to be called before streaming
  258.         // starts.  If it is not called, the object should perform any
  259.         // required initialization during a process call.
  260.         //
  261.         HRESULT AllocateStreamingResources();
  262.  
  263.         // Free anything allocated in AllocateStreamingResources().
  264.         HRESULT FreeStreamingResources();
  265.  
  266.         // GetInputStatus - the only flag defined right now is ACCEPT_DATA.
  267.         HRESULT GetInputStatus(
  268.                 DWORD dwInputStreamIndex,
  269.                 [out] DWORD *dwFlags // ACCEPT_DATA
  270.         );
  271.  
  272.         //
  273.         // Pass one new buffer to an input stream
  274.         //
  275.         HRESULT ProcessInput(
  276.                 DWORD dwInputStreamIndex,
  277.                 IMediaBuffer *pBuffer, // must not be NULL
  278.                 DWORD dwFlags, // DMO_INPUT_DATA_BUFFERF_XXX (syncpoint, etc.)
  279.                 REFERENCE_TIME rtTimestamp, // valid if flag set
  280.                 REFERENCE_TIME rtTimelength // valid if flag set
  281.         );
  282.  
  283.         //
  284.         // ProcessOutput() - generate output for current input buffers
  285.         //
  286.         // Output stream specific status information is returned in the
  287.         // dwStatus member of each buffer wrapper structure.
  288.         //
  289.         HRESULT ProcessOutput(
  290.                 DWORD dwFlags, // DMO_PROCESS_OUTPUT_FLAGS
  291.                 DWORD cOutputBufferCount, // # returned by GetStreamCount()
  292.                 [in,out,size_is(cOutputBufferCount)]
  293.                   DMO_OUTPUT_DATA_BUFFER *pOutputBuffers, // one per stream
  294.                 [out] DWORD *pdwStatus  // TBD, must be set to 0
  295.     );
  296.  
  297.         //  Locking - lock if bLock is TRUE, otherwise unlock
  298.         HRESULT Lock(LONG bLock);
  299. };
  300.  
  301.  
  302. //
  303. // Interface returned by the DMO enumeration API
  304. //
  305. [
  306. object,
  307. uuid(2c3cd98a-2bfa-4a53-9c27-5249ba64ba0f)
  308. ]
  309. interface IEnumDMO : IUnknown {
  310.     HRESULT Next(
  311.         DWORD cItemsToFetch,
  312.         [out, size_is(cItemsToFetch), length_is(*pcItemsFetched)] CLSID *pCLSID,
  313.         [out, size_is(cItemsToFetch), length_is(*pcItemsFetched), string] WCHAR **Names,
  314.         [out] DWORD *pcItemsFetched
  315.     );
  316.     HRESULT Skip(
  317.         DWORD cItemsToSkip
  318.     );
  319.     HRESULT Reset(void);
  320.     HRESULT Clone(
  321.         [out] IEnumDMO **ppEnum
  322.     );
  323. }
  324.  
  325.  
  326. // Flags for IMediaObjectInPlace::Process
  327. enum _DMO_INPLACE_PROCESS_FLAGS {
  328.     DMO_INPLACE_NORMAL = 0x00000000,
  329.     DMO_INPLACE_ZERO   = 0x00000001
  330. };
  331.  
  332. [
  333. object,
  334. uuid(651b9ad0-0fc7-4aa9-9538-d89931010741)
  335. ]
  336. interface IMediaObjectInPlace : IUnknown {
  337.  
  338.     // Proces - Given a buffer of size ulSize, put the output
  339.     // of the DMO into the same buffer.
  340.     HRESULT Process(
  341.         [in] ULONG ulSize,
  342.         [in,out,size_is(ulSize)] BYTE* pData,
  343.         [in] REFERENCE_TIME refTimeStart,
  344.         [in] DWORD dwFlags
  345.     );
  346.  
  347.     // Create a copy of the In-Place Media Object. This allows
  348.     // for very fast initialization of a number of In-Place objects
  349.     // in a known state.
  350.     HRESULT Clone(
  351.         [out] IMediaObjectInPlace **ppMediaObject
  352.     );
  353.  
  354.     // GetLatency - Returns a REFERENCE_TIME value
  355.     // (1 tick = 100ns) which corresponds to the latency time
  356.     // processing this effect will add to the graph. This assumes
  357.     // the effect cost per buffer is a constant.
  358.     HRESULT GetLatency(
  359.         [out] REFERENCE_TIME *pLatencyTime
  360.     );
  361. }
  362.  
  363. // Quality control status flags
  364. enum _DMO_QUALITY_STATUS_FLAGS {
  365.     DMO_QUALITY_STATUS_ENABLED = 0x00000001
  366. };
  367.  
  368. [
  369. object,
  370. uuid(65abea96-cf36-453f-af8a-705e98f16260)
  371. ]
  372. interface IDMOQualityControl : IUnknown {
  373.     HRESULT SetNow(
  374.         [in] REFERENCE_TIME rtNow
  375.     );
  376.     HRESULT SetStatus(
  377.         [in] DWORD dwFlags
  378.     );
  379.     HRESULT GetStatus(
  380.         [out] DWORD *pdwFlags
  381.     );
  382. }
  383.  
  384. // Flags for IVideoOutputOptimizations
  385. enum _DMO_VIDEO_OUTPUT_STREAM_FLAGS {
  386.     DMO_VOSF_NEEDS_PREVIOUS_SAMPLE = 0x00000001
  387. };
  388.  
  389. [
  390. object,
  391. uuid(be8f4f4e-5b16-4d29-b350-7f6b5d9298ac)
  392. ]
  393. interface IDMOVideoOutputOptimizations : IUnknown {
  394.     HRESULT QueryOperationModePreferences (
  395.         ULONG ulOutputStreamIndex,
  396.         DWORD *pdwRequestedCapabilities
  397.     );
  398.     HRESULT SetOperationMode (
  399.         ULONG ulOutputStreamIndex,
  400.         DWORD dwEnabledFeatures
  401.     );
  402.     HRESULT GetCurrentOperationMode (
  403.         ULONG ulOutputStreamIndex,
  404.         DWORD *pdwEnabledFeatures
  405.     );
  406.     HRESULT GetCurrentSampleRequirements (
  407.         ULONG ulOutputStreamIndex,
  408.         DWORD *pdwRequestedFeatures
  409.     );
  410. }
  411.  
  412.